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PREFACE 

This cocumenti which reflects the current state of the MSU 
Frontenc!* provides information about the Frcrtend necessary to 
those working with It or bin Iding their own Frcntend. The three 
classes of Frontenc! components ana the extent to which this 
document describes them follows: 

Modules. The crograms with which the user interacts during 
command soecif ication and which communicate with the tool: the 



Virtual Terminal Control (VTO* the Cocrmand Language 
Interpreter (CLI)* and the Process Communication Interface 
*"~ T * A description of CLI operation and of the FCI and VTC 



'P 
CPCI). 

is provided. Also included is 
representation types. 



a discussion of data 



Data Bases. The data bases and date structures associated with 
th > user interface machinery: the grammar* User Profile and 
Help data bases* User Statistics* CML source programs* and 
Command Seauences. More information on the data bases may be 
found in A GUIDE TO THE CML AND CLI CU. 

Auxiliary Tools. The auxiliary programs and tools that allow 
th =*- user or tool builder/installer to create* examine* or 
manipulate the above data bases: the CML compiler* User 
Profile tool* Help tool* Statistics Analysis programs* and 
Command Sequence Processor. A detailed description of the CML 
compiler and compacter and CML variable types is provided here* 
along with a section on the current anc future capabilities of 
th? User Profile tool and its data structure* 

The last section tells briefly hew to create and load a Frontend. 
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CLI OPERATION 

The CML Grammar 

A CNtL grammar consists of a series of instructions and 
associated tables. The grammar instru tions form a 
tree-structured program which the CLI interprets* It Is this 
process of grammar interpretation that oroduces the high 
quality user interaction for which the CLI is so well known, 

A CML grammar consisting of the two commands* 

celete COMMAND = "DELETE" ( "WORD" / "CHARACTER" )? 

insert COMMAND = "INSERT" C IF DISPLAY "WINDOW" / "WCRD" >; 

when compiled produces the following (upside down) tree 
structure : 



root of grammar tree 
I 



<1> 

"DELETE" 



(2) 

"INSERT" 



f 3) 

"WORD" 



(4) 
"CHARACTER" 



(5) 

IF DISPLAY 
I 
(7) 
"WINDOW" 



(6) 

"WORD" 



Each place in the tree where an instruction such as "WCRD" 
exists is called a node. Each node has been numbered for 
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reference, No* 
because there 



-•es 3* 4t 7* and 6 are celled terminal nodes 
: s nothinc following t h e *i in the tree. 



CM L Grammar Interpretation 

The CLI implements the command language described by a grafrmar 
by interpreting the instructions contained in the grammar* The 
CLI begins at the root of the grammar tree and simultaneously 
processes the various paths through the tree to terminal nodes. 
One such path is through nodes 1 and 3* another is through 2t 
5t and 7, Completing the processing of a terminal node such as 
none 3 is synonymous with command completion and causes the CLI 
to begin processing again at the rcct cf the grammar tree. 
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ML COMPILER AND COMPACTOR DESCRIPTION 



Introduction 



The CML compiler and CML compacter are used to trarsforp the 
text of a CML grammar into a form executable by the CLI. The 
CML compiler takes as input a source file* either an NLS or 
text file* and produces as output a file containing an 
appropriate set of CML instructions. The CML compacter is a 
post-processer for the compiler which reduces the size of the 
compiler output and produces any modifications necessary for 
the grammar to run on its target machine. 



The following discussion assumes that 
with the CML and L1G languages. 



the reader is familiar 



The Compiler 

The CML compiler is written in Tree Meta* a compiler-writing 
language* and runs en the PDP-10. It can be run in NLS taking 
as input an NLS file* or from the EXEC with a text file as 
input* 

The format of the compiler output is a directed graph whose 
nodes are instructions* each of which occupies two 36-bit 
words. The links in the directed graph are implemented through 
twe fields in each instruction — the alternative field and the 
successor field. The alternative fielc contains the address of 
the CML instruction to execute in parallel with this one? while 
the successor field contains the address of the next 
instruction to execute should this one succeed. 

Another field in each instruction indicates the type of the 
instruction* such as "recognize a command word" or "call an 
execution function". Other fields contain information 
dependent on the instruction type. For example* the "recognize 
a command word" instruction has a field which contains a 
pointer to the command word string. 

The compiler output is a relocatable file which must be 
tink-tcaded before being used. 
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The Comoacter 

Overview 

The compacter is written in the L10 language and runs on a 
PDP-10. The Input to the cosoacter is the compiler output 
file; its output is a compacted graimar file* The compacter 
further processes the output of*the compiler to reduce its size 
and put it into a form appropriate for the type of computer 
that it will be running on. As a result* there are two 
compacters* one for producing grammars to run on the PDP-10 and 
on* for the PDP-11. 

The output of the two compacters differs in only two ways. The 
first is the dispatch record at the beginning of the grammar* 
This record is specially formatted for the PDP-11 so that the 
sa^e L10 RECORD definition can reference it on both the FDP-10 
and PDP-11. 
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All further discussion of the ccf&pacter applies tc both the 
PDP-10 and PDP-11 compacters. 

A compacter operates by loading the relocatable file produced 
by the compiler* together with any related parse function 
files. Thus* the grammar has all of its references resolved 
and may be put into a form that need not be link loaded. Upon 
completing the compaction processing* the newly-prcduced 
compacted grammar is written on a file* 
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Compacted 3r3!nmar DescMotion 

Overall Structure 

A compacted grammar consists of two segments: a code segment 
and a data segment- The code secient contains the dispatch 
record* various tables used by the grammar* and the CML 
instructions. The data segment contains the grammars 
variables and process records. 

The Code Segment 

The first item in the code segment is the dispatch record. It 
contains pointers to the tables in the segment? byte numbers of 
certain instructions in the grammar* ard other information 
about the grammar* Pointers are relative to the beginning of 
the segment starting at 0* the byte numbers are relative to the 
beginning of the segment starting at 1" a byte number 
indicates the absence of an instrtctior. The dispatch record 
has the following L10 RECORD definition: 

Csubr) RECORD % grammar dispatch record % 

subnameC ADDRESS3* % pointer to subsystem name string X 

firstinst CADDRESS3* % byte number of first instruction of 
commands % 

valcodeCADDRESS2» % validation code - 10 for the PDP-10* 
11 for the PDP-11 % 

h I pruleC ADDRESS2* % grammar help rule / indicating none % 

initinstCADDRESSIU % initialization rule / T 

reeninstC ADDRESS]* % reentry rule / % 

termruleUADDRESS 3» % termination rule / % 

prsrecC ADDRESS 3* % pointer to process records relative to 
beginning of DATA segment / indicating none % 

kwordC ADDRESS]* % pointer to ccmmard word table % 

echoworciC ADDRESS 3* 2 pointer to noise word string table % 
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execvector CAD0PESS3* % pointer to execute byte number 

tsole l ' 



r^ f ( ;n e- 



ncs CADDRESS3* % pointer to parse function address table 



funcs CADDRESS3* % pointer to function record table * 

gvstart CADDRESSj* % pointer to global variables relative 
to beginning of DATA segment % 

sharl CADDRESSJ* % number of 32 word blocks in code seament 



oriv CADDRESS3* % not used % 

erivl CADDRESSj* % number of 32 word blocks in data seament 



pfcsizef 8 1 % number of 32 word blocks in parse function 
cooe %t 

pfdsizeC 9 3% number of 32 word blocks in parse function 

M ^ 4- a V J 

Following the dispatch record in the code segment are the CHL 
instructions. If an instruction has an alternative 
instruction* it is always the next instruction. The successor 
of an instruction* if it has one? always follows the 
instruction* although it is not necessarily the next 
instruction. Instructions are coded into 8-bit bytes* There 
are byte numbers for certain of these instructions — e.g.* the 
first instruction of the commands~-in the dispatch record. A 
description of the instruction format is given below in 
"Compacted Grammar Instruction Format"* 

The tables for the grammar follow the instructions. With one 
exception* an entry in any table consists of a pointer relative 
to the beginning of the code segment. The single exception is 
the execute byte number table Cpointed to by the ♦execvector* 
field) whose entries consist of the byte number of an 
instruction relative to the beginning cf the code segment. All 
t^ble entries occupy a full computer word. 

Following the tables are various constant data elements used ^y 
the grammar* e.g.* command word strings. Command words defined 
as selectors are slightly different from other command words* 
in that the three words previous to the command word string are 
indices into the psrse function table* These indices indicate 
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th~ selection parse functions to be used to gather a selection 
by po^ntinn. typing in* an6 typing the address. The order of 
the three words ^ s : 

point selection parse function irdex 

type in selection parse function index 

type address selection parse function incex 

command word string 

Th* 1 selection parse function may be built into the CLI* as with 
a TEXT selector for example* or may be written by a CML 
programmer. A zero index indicates that selection by the 
corresponding method is undefined. For example* a zero for the 
point selection oarse function index scans that the selection 
cannot be pointed to. 



The Data Segment 

The data segment of a compacted grammar contains those elements 
which may change during the use of the grammar* this prevents 
it from being shared among multiple users of the grammar as is 
the code segment. 

The first elements in the data segment are the grammar 
variables. During execution of the grammar* these elements 
will contain pointers to the actual values of the grammar's 
variables. Typically* these point into the free space area of 
the CLI. The variables are divided into two Groups: local 
variables followed by global variables^ 

Following the variables in the data segment are the process 

re^OrdS TKapo o •>» a. -f r» t » »» u n r»ri r»o/*ri»»r<c>* rt r* a •fni* a s r» $■* K » r» lr «s ft H 

P 

g 
t 




Compacted Grammar Instruction Format 

E^ch CHL instruction consists of one or more contiguous P-bit 
bytes. The first byte of an instruction always indicates its 
type. Following the first byte there may optionally be one or 
more bytes of fields related to the instruction type. In 
addition* there may optionally be one cr two bytes of successor 
field. 
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Th~ : first byte of sp instruction has three fields* defined as 
an Ll r : RECCRD c-s follows: 

Mnstre*') RECORD cccodeCrl* altsucC?]* UcmcCll? 

The ♦opcode* field indicates the instruction type* e.g. 
♦recognize a command word* or f call an execution function** 
The *llcmd* field is used by different types o.f instructions in 
different ways. For example* the ♦recognize a command word* 
instruction uses it to indicate whether its command word is 
first level or not* 

The f altsuc* field* together with the optional successor field* 
provides information about the instruction's alternative and 
successor instructions. It may assume the following values* 
which are defined as external constants in the CLI: 

notlast — The instruction is not the last alternative and its 
alternative instruction is the next instruction following it. 
A successor field indicates the successor's location. 



lastnone--The instruction is the last alternative* i 
has no alternative and no successor. 



e** it 



last* leld-- The instruction is the last alternative and its 
successor is indicated by its successor field* 



lastnext--The instruction is the last alternative 
successor is the next instruction* 



and its 



A successor field may be used to indicate the location of an 
instructions successor* Whether or net an instruction has a 
successor field is indicated by the •altsuc* field in the first 
byte. A successor field contains the cisplacement of the 
successor instruction relative to the last byte of the 
successor field. A displacement of 3 would mean that the 
successor instruction begins at the third byte following the 
last byte of the successor field* A z ro successor field 
indicates that the instruction has no successor. 

A successor field may be one or two bytes long? its first byte 
has two fields with the following L10 RECORD definitior: 

Csucrec) RECORD sucaddC71* longCll* 
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If the Hone' field ecuals Of the value of the successor field 

is simply the value of the •sucadd* field* If the »long* field 

equals If *here are two bytes of successor field. The value of 

t h : field is 

value = < sucadd field * 256 ) + second byte of field 

Other fields in instructions are often indices into one of the 
grammar tables. Table indices always start at 0. They ere 
used to computf the absolute addresses of various grammar 
elements. For example* to compute the absolute address of a 
command word in the grammar given its index »ind f » the 
following steps are taken: 

1. Compute the address of the beginning of the command word 
table *comwcrctab* • given the address of the beginning of the 
code segment *codseg*<* and usinc the 'feword* field of the 
grammar dispatch record: 

co^wordtab _ codseg + tcodseg 3. kwo rd ? 

2. Compute the absolute address of the command word 
*comwordaddr ? : 

comwordaddr _ codseg + Ccomwordtab 1C indl? 

So*e fields in instructions are variable designators. These 
are used to locate variables referenced by the grammar. An 
8-bit byte used as a variable designator is formatted according 
to the L10 RECORD declaration 

iaodrrec} RECORD varindC63* vartypeC dummyCll* nctlocalCll 3* 

If the f notlocal » field equals 0* the variable is and the 
entire byte *s an index whose base is the beginning of the 
grammar data s-cment. If the 'notlocal* field equals It the 
♦v'rtype* field is used to determine whether the variable is 

global — meaning the »varind f field is an index into the data 
segment with base indicated by the dispatch record field 
*gvstart*» or 

bltin — meaning the variable is built in to the CLI ard 
'varind 1 is an index into the CLI*s array of built-in 
variables. 
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Instruction Tyres 

Th? instruction ty pes--def ined as external constants in the 
CLI — ?rd the format of their bytes are described below. All 
instructions use the *oococe* and ♦altsuc* fields* These 
descriptions co not include the successor field* which way or 
may not be present in a particular instruction* The value of 
thp instruction types in octal is given in parenthesis. 

abortop (0). Show the user the contents of the CLI 

"ccuirutator and abort the command. 

first byte: (instrec) RECORD pcodeC52* altsucC23t 

UcmdClK 

Mo other fields are used. 

fceyoo Cl>» Recognize a command ord. The command word 
may be a literal* or a variable containing a string* or a 
list of strings. 

first byte: (instrec) RECORD cpcodeC53t attsucC23» 
UcmdCin; 

llcmd — this field equal to 1 implies command word is 
first level. 

second byte: This entire byte is interpreted 
differently depending on the *kwvar* field in the third 
byte and is either: 

an index into the command word table if the command 
word is a literal* or 

a variable designator if the command wore is a 
variable • 

third byte: Cvalrec) RECORD ntmofargsC tstrelC3j« 
tstintCl3* tstnotm. f i I lerCl :3* hashelprt leC 13. 
kwvarT 13* 

fcwvar — this field equal to implies that the second 
byte contains an index into the command word table 
and the entire third byte is the integer token 
associated with the command word. This field equal 
to 1 implies that the second byte contains a variable 
designator and the remainder of the third byte should 
be ignored. 



Augmentation Research Center 



PEce 11 



DIA LLG ANDY 3-FEB-77 17:06 28745 
Frontend System Gccumentati on 



No other fields are usee* 

con-firm (2 5. Cet a confirmation frcr* the user* e*c»* by 
the user typing a COMMAND ACCEPT- 

first byte! (instrec) RECORD cpcodeC5]* altsucC27* 

iicBidcib; 

No other fields are used. 

ssel? dsel* Isel (3* 4* 5)» Get a source* destination* 
or literal selection from the user. 

first byte: (instrec) RECORD -pcodeCSlt altsucC23* 
llcmdCli; 

No other fields are used. 

pusharg (&)• Push the CKL value in the accumulator onto 

the argument stack. This is the method by which 

arguments are gathered fcr parse or execution function 
ca 1 1 s. 

first byte: (instrec) RECORD cpcodeCSD* altsucC23* 
llcmdCU* 

No other fields are used. 

answer (?)• Get an answer from the user* e.g.* by the 
user typing H y n for "yes". 

first byte: (instrec) RECORD cpcodeC53* altsucC23* 
llcmdfli; 

No other fields are used. 

option (108). Get an OPTION character from the user. 

first byte: (instrec) RECORD cpcodeC53* altsucC23» 
UcmdriK 

Mo other fields are used. 

pfcllop CllB). Use a oarse function. 

first byte: (instrec) RECORD cpcodeC53» altsucC23» 
UcmdCl K 

Mo other fields are used. 
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second byte! entire byte is an index into the perse 
function address table. 

third byte: (valrec) RECORD HLmofargsC tstrelT3J« 
tstintfl3« tstncttl3? fillerCl~3» hashelp ruleC 13* 
VwvarCt3; 

numofargs — the number of arguments that the parse 
function is to be OPENPORTed with. 

No other fields are used. 

execute (12B)» Execute a series of CML elements. 

first byte: (instrec) RECORD cpcodeC5J» altsucC23» 
UcmdCll; 

Ho other fields are used. 

second byte: entire byte is er index into the execute 
byte number table. 

call (138). Call an execution function. 

first byte: CinstreO RECORD cpcodeC53* altsucC23t 
llcmdCin; 

llcmd — this field ecual to 1 implies that the 
function is to be called in "out of line 11 mode. 

second bytei entire byte is an index into the function 
re cord table. 

third byte! <valrec) RECORD ntroofargsC tstrelE33« 
tstlnttlD* tstnotClJ, fillerClil* hashelpruleC 13* 
kwvarC 13 % 

numofargs — the number of arguments that the function 
is to be called with. 

No other fields are used. 

fbclear (1^8). Clear the feedback window. 

first byte: finstrec) RECORD cpcodeC53» altsucC?3« 
llcBidCil; 

No other fields are used. 
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ut a noise word strina in the feedback 



first byte: (instrec) RECORD cpccbeL5]* altsucC2J* 
1 1 c m d E 1 3 « 

Ho other fields are used* 

second byte: entire byte is an index into the noise 
word string table. 

recho (168). Remove the last item from the feedback 
window and put in a noise word string. 

first byte: (instrec) RECORD cpcodeC53» altsucC23* 
UcmdCll: 

No other fields are used. 

second byte: entire byte is an index into the noise 
word string table. 

storecp (178). Store the CML value of the accumulator 
into a CML variable. 

first byte: (instrec) RECORD cpcodeCSj* altsucr23» 
HcmdCia; 

Mo other fields are used. 

second byte: entire byte is a variable designator. 

load (20P). Load the accumulator with the velue of a CML 
variable* 

- first byte: (instrec) RECCRD cpcooeC53* altsucC23* 
HcmdCl3; 

No other fields are used. 

second byte: entire byte is a variable designator. 

enter (21B). Enter a number intc the accumulator. 

first byte: (instrec) RECCRD cpcodeC53» altsucC23* 
-llcmdCll? 

Mo other fields are used. 
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second byte: entire byte is the number tc enter into 
the accumulator. 

test (225) ► Test the value of the accumulator. 

first byte: (instrec) RECORD cpccdetSj* altsucC23« 
UcmdCli; 

Mo other fields are used. 

second byte: entire byte is interpreted differently 
depending on the 'tstint* field in the third byte. The 
second byte is either: 

an integer to compare the accumulator witht or 

a variable designator to compare the accumulator 
with . 

third byte: Cvalrec) RECORD numofargsC tstrelC33* 
tstintCll* tstnotCl3» fillerClllt hashelpruleC lit 
kwvarCll? 

tstrel — the relation which is being tested for. The 
following* which are declared in the CLI? are 
possible values: 

equal 

greater 

less 

grequal 

lessequal 

tstint — this field equal to 1 implies the test is an 
integer test and the second byte contains the 
integer. This field equal to implies a test 
against a variable and the second byte contains a 
variable designator. 

tstnot — this field equal to 1 implies that the result 
of the test should be complemented. 
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showcp (236). Show the contents of the accumulator to 

the user- 
first bytet (instrec) RECORD opcoceCS It altsucT23. 
llcflRdr 11; 

No other fields are used* 

entercw (24B). Enter into the accumulator a command 
word. 

first byte: (instrec) RECORD cpcodeC5D» altsucC2J? 
UcfndCi3* 

Ho other fields are used. 

second byte! the entire byte is an index into the 
command word table. 

third -ytel the entire byte is the integer token 
associated with the ccmmanc word. 

^nternull (258). Enter into the accumulator a Nl'LL. 

first byte: (instrec) RECORD cpcodeC53* altsucC23* 
UcmdClK 

Mo other fields are used* 

rntertrue (26B). Enter into the accumulator a TFUF. 

first byte: (instrec) RECORD cpcodeC53« altsucC2J« 
UcmdClT; 

No other fields are usee. 

enterfalse (278). Enter into the accumulator a FALSE. 

first byte: (instrec) RECORD cpcodeC53* altsucC23« 
UcmdCU; 

Mo other fields are used* 

resure (30B). Resume a help call. 

first byte: (instrec) RECORD rpcodeC53« altsucCPUt 
llcmdCll? 

No other fields are used» 
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Bpperd f31E). Append the value cf the accumulator to 3 

CML variable. 

first byte: (instrec) RECORD opcotieC53« altsucC'lt 
Ucffc!Il3; 

Wo other fields are used. 

second byte: entire byte is a variable designator. 

testtrue (3285. Test to see if the accumulator is TRUE. 

first byte: (instrec) RECORD cpcodeC53* altsucC23* 
UcmdCii; 

llcnrd — this field equal to 1 implies that the result 
of the test should be complemented. 

testnull (338). Test to see if the accumulator is NULL 
ar FALSE- 

first byte: (instrec) RECORD cpcodeCSJ* altsueC23» 
Ucn?dLl3; 

llcmd-- this field ecuat to 3 implies that the result 
of the test should be complemented • 

helpcall (348). Call an execution function that has 
specified a help rule* 

first byte: (instrec) RECORD cpcodeC53» altsueC23» 
llcmdCl3; 

Ho other fields are used* 

second byte: entire byte is an index into the function 
record table. 

third byte: (valrec) RECORD ntmofargsC tstrelE33* 
tstintClD, tstnotEliW fillerCl33* hashelpruleC 1 3- 
kwvarC 13? 

numofargs — the number of arguments that the function 
is to be called with. 

No other fields are used. 
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fourth byte: the entire byte is an incex Into the 
execute byte number table indicating the -Mrst 
instru'ticn of the help rule. 



example 

The followine provides a comparison between a CML grefinar 
source and the corresponding compacter output. The source 
is: FILE cmlexp Knsw-sources»cgciU> 
<poggio»cmlexp»cmlt>% 
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". Declarations % 

DECLARE COMMAND WORD 

"SHOW"* 

"CML" = 1* 

"CLI W = 2* 

DECLARE VARIABLE var? 

DECLARE FUNCTION doexample? 

SUBSYSTEM cmtexp KEYWORD "EXAMPLE" 

exp COMMAND = "SHOW" var _ ( "CML" / "CLI"!L2! > 
< M example"> doexampleC var ); 

EMD. 

FINISH 

The ccnoaeter output is shown in octal 8-bit bytes. 
Instruction boundaries are Indicated by dashes* 



341 



Recognize first Level command word "SHOW". This 
instruction has no alternative and its successor is the 
n?*xt instruction. 



"SHOW" is the third entry in the command word table. 



Its integer token is because none was declared 
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01 



^-ognize first level command word R CHL B . This 
instruction has an alternative which is the next 
instruction. It has a successor field which indicates 
the location of the successor. 



B CML tt is the second entry in the command word table. 



Its integer token is 1 •■ 



This is the successor field. he 'long* field of the 
oyte is 0* indicating that the successor field is only 
1 byte long. The successor field has a value of 4» 
indicating that the successor begins at the fourth byte 
following this one. This is the 157 byte* the first 
byte of the store instruction. 



241 



Recognize second level command word "CLI". This 
instruction has no alternative and its successor is 

next. 



'CLI B is the first entry in the command word table. 



Its integer token is 2. 
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Store the contents of the accumulator into the variable 
* V3r f « This instruction has nc alternative arc its 
successor is next. 



The »notlocal* field equals Implying that this is a 
local variable* It is the first local variable in the 
data segment* 



155 



Show the noise word "example" to the user* This 
instruction has no alternative and its successor is 
next. 



The noise word "example" is th 
noise word table- 



first entry in the 



160 



Load the accumulator with the contents of the variable 
'var'. This instruction has no alternative arxi 4 ts 
successor is next* 



The •notlocal* field equals Q implying* that this is a 
local variable* It is the first local variable in the 

d~ta s earner. t» 
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Pu^h the contents of the accumulator onto the r-rouinent 
stsck* This instruction has no alternative and its 
successor is next* 



53 



Call the execution function "dcexample". This 
instruction has no alternative and no successor, 



The execution function w doexample tt is the first entry 
in the function record table. 



The *nuffiofargs» field eouals 1 indicating that one 
argument should be popped off the argument stack and 
oessed to the execution function. 
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CML VARIABLE TYPES 



Introduction 



This section describes the Commend *!eta Language (CML) variable 
types and their translation into PCP typ~s. It is intended for 
CML parse function writers but may be of interest to anyone 
familar with CML. 



CML Variable Structure 

CML variables all contain a pointer to a block of one or more 

continuous words of memory. Th*? first wcrd (word 0) o* the block 

is always a heaoer with the following fields right adjusted in 

word : 

******************************************************** 

* * * * 

* vlength (8 bits) * vmarks (2 hits) * vtype (6 bits) * 

* * * * 
********************************************* *********** 

As their neies suggest* the vlength fielc indicates the variable 
length and the vtype field the variable type. The virarks field 
indicates hew many marks were made on th display during the 
creation of the variable? its value* typically zero* will depend 
on how the variable was created. 

The header fields are defined in Lie as: 

(v?r) RECORD ^header of a variable% 

vtyoeTcD* vmarks£23* vtengthC83» 

CML Types 

STRING 

word o: vtype = strtype C= 1>» vlength = 3 

word i: integer token associated with string or if none 

word ?: address of L10 strinc 
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COMMAMD WORD 



worn 
wore 1 
word 2 



vtype = cwtype {= 2)? vlength = 3 

integer token associated with string or if none 

address of L10 string 



The distinction between a command type and a strinc type is 
th3t a command word string may have been defined tc be a 
SELECTOR. In this case the three words previous tc the string 
may point to selection functions for pointing* addressing* and 
typing in. This fact may be generally ignored by the CML 
programmer * 

INTEGER 

word o: vtype = integer C= 3)* vlength = 2 

word i. : the integer 
POINT 

word 0: vtype = pointtype (= 4)* vlength = 5 

word i; the window identifier 

word 2: the string identifier 

word 3: the line segment identifier 

word 4: the character position 
ADDRESS 

word 0! vtype = addrtype <= 5)* vlength = 4 

word i: integer token associated with string or if none 

word ?: address of L10 string 

word 3: window identifier 
MULL 

word o: vtype = nulltype f = 6)* vlength = 1 
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LIST 

wore c: vtype = llsttype <- 7)* vlength -2 +■ number of 
elements In list 

word i: number of elements in the list 

word 2 to worn ft: addresses of elements in the list (elements 
may he of any type) 

TRUE 

word o: vtype = truetype ( = 8)* vleng h = 1 
FALSE 

word c: vtype = falsetype < = 9>» vlencth = 1 
BLOCK 

wore 0* vtype = blocktype C= 10>« vlength = number of bits in 

block 

word ! to word NZ the bits (32 per 36-bit word left-adjusted) 
WINDOW 

word o: vtype = windtype (= ID* vlength = 2 
word i: the window identifier 

ADDRESS EXPRESSION 

word or vtype = adexptype (= 12)* vie gth = 2 ♦ number of 

elements 

word i: number of elements in the address expression 

word ? to word n: addresses of elements in the address 
expression 
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VIRTUAL TERMINAL CONTROLLER DESCRIPTION 



Int rocluct i on 

The Virtual Terminal Controller (VTC) module of the Frontend 
oresents a virtual terminal interface to the tools and the 
Frontend itself. It contains the procedures and data to map the 
virtual operations into the actual operations necessary for 
communication with the connected terminal device* 

The VTC oefines three classes of terminals: CD half duplex 
(possibly line at a time) typewriters* (?) full duplex 
typewriters* and (3) alphanumeric display terminals* perhaps with 
pointing devices* etc* A set of operations are defined for each 
class o* terminal. Because operations are the same for classes 1 
and 2« tools address themselves to two virtual terminal types: 
typewriter an<\ display* More advanced graphics terminals fall in 
a fourth class* but the operations for this class are not yet 
specified* 

The VTC functions as a service module in the FE* When a call is 
*ade on the VTC* it performs some specified function ana returns* 
The VTC is accessed through one of two entry point procedures* 
which in turn call on the other VTC procedures* One entry 
procedure is used only by the Frontend to manipulate the terminal 
in some tool-independent fashion* the other is used when a tool 
explicitly calls on the VTC* 



VTC Design 

This section describes VTC capabilities and the design approach 

to the VTC. A glossary of terms usee in this description may be 

found at the end of this chapter* 



CsDabi li ties 

For typewriter terminals* VTC capabilities consist of setting 
the terminal device type? writing strings on the terminal* and 
controlling the carriage position* 

A rich set of primitives exists for the display class cf 

terminals* many of which rely on the concept of a display 

"window"* Several windows are predefined by the Frontend and 

created by the FE through VTC primitives: 

A TT Y-simul ation window for status or error messages. 
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A command feedback window. 

One or more tool windows. 

a special small window for tool mode inf creation * 

These windows are created by the Frontend proper by way of VTC 
primitives. 

Th^ screen may contain adjacent and overlapping wireows* much 
the way a person views several pieces f paper on his desk. 
Each window has an associated priority to determine which 
window is visible when the windows overlap. 

Tools are given custody of a window* celled a primary window* 
when they are first started. The tool is then free to write 
and delete strings in the window* clear the window? and create 
more windows within it. Typically the primary window is nearly 
all of the screen (e.g.* 20 out of 24 full lines). 

A user can maintain separate primary windows for many tools 
concurrently by instructing the Frontend to divide an existing 
window. Primary windows may not overlap and can only be 
reconfigured and written by the owning tool. Within the 
boundaries of a primary window* a tool may create overlapping 
windows. 

yhen using a display terminal* the user can select any text 
visible to him instead of typing it on the keyboard. This* 
combined with the ability to run seversls tools in different 
windows concurrently* gives the user a helpful cross-tool 
facility. 



yhen a tool is terminated* via a call to *tootrst»* all 
assigned during the tool's use are released. The data 
structure tool list (tlist) is used to find the windows 
associated with the tool* given the tool code. 



windo ws 



Design Approach 

The VTC is comprised of a collection o* service procedures and 

a data base. The data base contains structural anc textual 

information about the screen contents which the procedures 
manipulate in useful ways. 

The data base consists of a minimum of "global" information 
th st is always present* for the most part runtime-allocated 

blocks of data? of variable size* that describe the structure 
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and contents of the windows. This frees memory when not in 
use« and flakes possible a more efficient use of memory bv 
sharing the allocation pool among many Frontend processes. 




VTC Implementation 

This section briefly describes the nature of the VTC interfaces* 
data structures* storage management techniques* erxc error 
handling strategy. It provides references that will be useful in 
locating functional areas within the source code* 

Display Package Interfaces 

The VTC module has three logical interfaces- the external tool 
interface- the internal CLI interface* and the terminal device 

interface. 



A call generated from the CLI is of the form 

DPYCALL (name* n. al» »..an) 

where name (an integer) is an internal VTC procedure number* 
and n is the number of arguments al through an. 

The procedure DPYCALL calls the specified internal display 
procedure (aany of which correspond one-to-one to the external 
procedures* but with the arguments in a different form). The 
procedure list is in array IDPYTAS. The association between 
th^ procedure name and its number is shown. 

(scrollwindow = 1)— scroll a window. 

(getdstr = 2) — get display string from display structure. 

(toolset = 35 — set a window to be given tool*s primary 
window. 

(toolrst = 4) — remove toot from tool list. 
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f wrtl. s-t z 5>--write Line segment. 

(delstr = fe ) — delete a string. 

'dellsg = 7)--tielete line segment. 

Crpllsc = 8) — replace line segment* 

(ppointsel = 9) — point selection routine. 

(xywindow = 10)--given x* y real coordinates* return 
window-id. 

Cwrtstr ~ 11* — write string. 

(crew^nd = 12) — create window. 

(intseqw = 13) — initialize secuential window. 

(setdftty = 14> — set default TTY window. 

(?w3tt = 15) — set window attributes. 

(setsatt = 16) — set string attributes. 

'inwind = 17) — determine if a "window-relative" point is in a 
window. 

fsetlatt = 1?-) — set linseg attributes. 

(delwind = 19) — delete window given window-id. 

(celsubs = 20) — delete all sub-windovs given wincow-id» 

Cclrwind = 21> — clear window* given 'indow-id. 

(markfcn = 22) — mark screen to show cr remove a selection. 

fwrtliterat = 23) — write literal string in a window. 

Cwrtpart = 24) — write partial string? subordinate to 
wrt li ter?l. 

(finish = 25) — finish display manipulation sequence. 

C-slls to the display package from tools are external procedure 
calls as defined in Appendix 4 of A GUIDE TO THE CML AMD CLI. 
The CLT transforms that into a call of the form 
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EOPYDSPf iport, cpert) 

wn-re the two arguments are port-identifiers for scurce and 
s^nk of the current data representation 'arguments and 
results). The display package procedures read their arguments 
and qenerat th^ri results usina the twc port-icenti tiers . 



VTC Routines Available through the CLI 

The procedure EDPYDSP dispatches external calls to the 
correct procedure* passing two coroutine port-ids as 
arguments* one for the coroutine that supports reading 
argument lists (rlist) and one for writing result lists 
Cwlist). Each procedure reads the PCPB8 argument list* 
performs some function* and then writes a PCPB8 result list. 

The procedure nases below are those found in the source code 

of the VTC module. 

(ecrewind) — create window. 

(eclrwind) — clear window. 

Cescroll) — scroll window. 

Cewrtlsg) — write line-segment. 

Cede I wind) — delete window. 

Cewrtstr) --write string. 

Cecel Isg) — delete line -segment. 

(ecelstr) — delete string. 

Cerpllsg) --replace line-segment. 

(swrtlit) — write literal into window* 

Ceset sett )--set string attributes. 

(esetlntt) — set line-segment attributes. 

Ceposstr) --reposition string. 

( epos lsg> — reposition line -segment • 

Ce rolstr) -^-replace string. 
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Cebatch) — batch commands processor 

(SGetwindows >--gpt window information* 

(etrack) — turn cursor tracking on/cff for graphics 
terminal. 

The VTC external procedures are callable through a set of 
externally callable routines in the FE. The list of user 
callable procedures with their arguments and results are 
described in A GUIDE TO THE CML AND CLI. Appendix 4. 
"Externally Callable Procedures in the Frontend". 

Terminal Device Interface 

Keyboard and Line Processor input is performed by the procedure 
•dinptc*. which makes use of the following procedures: 

^dinptc) — single character input routine* 

f Lpgetcharl— I ine processor GETCHAR routine. 

Cangetchar) — getchar for alphanumeric displays. 

(ancnv) — alphanumeric display convert typein to coordinates. 

(dinbc)--read a big character. 

(dinbcl) — read mouse button changes. 

Display and Line Processor manipulation is performed by the 
following procedures. They are called by various VTC 
orodecures to manipulate the terminal device. 

(andspstr) — display string on alphanumeric display* 

fpad>— pad with given number of null characters. 

Canreset) — reset alphanumeric display. 

(position) — position cursor - alphanumeric displays. 

(trnslz) — translate coords for alphanumeric display. 

(cscreen) — clear screen - alphanumeric displays. 

(track) — resume tracking - LP displays. 
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( rt r^ck ) --resume treckinc - LP displays. 

feline) — write blanks - alphanumeric displays. 

Celine) — delete line - alphanumeric displays. 

(inline) — insert line - alphanumeric displays* 

(standout) — Send stand out command - alphanumeric displays. 

(endstanoout ) — Send end stand out command - alphanumeric 
di splays. 

C lpttywintiow)--speci f y default tty - LP terminals. 

c realcds ^--convert relative coorcs tc real, screen coords. 

tlsgtrncate) — line segment truncate function. 

fsndlsc) — send line segment to terminal. 

<doysout) — display string output with control chars. 

Special VIC Data Elements 

The primary data elements are summarized here and described in 
detail in the code file. Below is a list of important data 
elements? with their corresponding names as found in the source 
code. In some cases? further description can be found in the 
glossary at the end of this chapter. 

User information 

(userinfo) RECORD — Each userinfo record contains informtion 
that is referenced during a terminal session* It contains 
terminal specific information* the tool-list address* and the 
window-list address. 

Tool-list 

(tlist) RECORD — A list of tool code and primary window-id 
pai rs. 

Window t?ble 

<wtab) RECORD— Each entry contains window size and location 
fields? priority* type* attribute list address* parent 
window-id* and bookkeeping for the contents of the window. 
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" 1 1 r i h u t e W c r d 



(*tts> RECORD — E5C 
r 



include visibility kj.vi if 8 mm-<. 
(text string or coordinates)* 



h word contains attributes for linsegs 
strings or windows). The attributes 
and high-lighting* the type c 
" - • ■ - - an: j selector code. 



or 



uns of linsegs (strings or windows). 

i 4. .. -~^ u r~u_ i .s~u * j — 4.u« *. f obsignation 



t rinc-li st 



(slist) RECORD — Each element contains a string attribute 
word* a linseg-list element address* and coordinates for the 
origin of the string. 

Lins°g-list 

flslist) RECORD — Each element contains a linseg attribute 
word* the address of the text string* and the coordinates of 
the origin of the linseg origin. 

Garbage list 

fgarbgr) RECORD — each element contains a wincow-id and 
coordinates and character counts suitable for clearing 
lensegs from the screen. 

Delayed write list 

fdlyrec) RECORD — each element contains window* string* and 
linseg-id information for deferred updating of the screen. 

Hark block list 

(markr) RECORD--each element contains mark type* window-id* 
string-id* a pair of linseg-ids* and a pair of character 
counts used to record a marked (bugged) entity. 



Storage Management 

Storage management is handled by a stardard package of routines 
that is used by most L10 modules. Interface to the package is 
provided by the procedures below. They assume that a storage 
management zone "doyzone" has been initialized through a call 
to "makezone" * a procedure in the storage management package. 

fgetdpy) — get block of storage from cpyzone. 

Cfredpy) — free block of storage from cpyzone. 
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Error Handling 



Errors ar 
may occur 



handled via the 
!n any procedure 
catchphrase encountered up 



si~ nailing facility. 



Ar ebort 



LI 

and may be ncted upon in any active 
the thread of control. Aborts are 
generally ignored until they reach the top level dispatching 
routine Cdpycall or edpydso)* at which time (finish) is called 
fcr cleanup. 



Glossary 

big character 

An element cf the Line Processor proto«"ol--a secuerce of 
characters in the terminal stream that begins with <£SC>. Used 
in conjunction with Line Processor terminals to send pointing 
coordinates and special characters. 

coordinates 

The horizonal <x) and vertical (y) displacements from the 
origin (lower Left corner) of a window* 

delayed writes 

The method used to optimize display manipulation sequencing by 
doina all "writes" last. The writes are recorded in a list 
pointed to by dlyblk. Delayw( windtab * str* Isg) will record 
entries and wrtdely (TRUE) will actually do the writes. 
Wrtdely (FALSE) will delete the records without writing. 

garbage List 

A linked set of garbage blocks with "sizg" garbage elements in 
each. Each garbage element indicates a string of garbage that 
is on the screen and must be cleared sometime. Each element 
looks like "garbgr 1 *. Global "garbg" contains the address of 
the first block. Word zero of each block contains the address 
of the next (or zero if the last block >• 

linseg-id 

Identifier for a line segment Clinseg) in a specified string. 
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linseg-List 

A t^st of tinseg element records* one for each linseg in a 
given string. Each element points to text string, 

■vark block 

An allocated block which defines a selection mark en the 
screen: "markit" creates them and "popmark" uses them to 
remove the marks. They are then linkec in reverse order 
through userinf cmark (i,e,» the most recent mark is first in 
the link). See userinfo and markr* 

selector code 

An 8-bit number that indicates the selectivity of strings on 
the screen. Three values are given semantics by the Frontend? 

zero and one! Only selectable as literal CLSEL), 

two: NEVER selectable as Literal CLSEL) except across tools 

(SSFL and DSEL okay) . 

greater than two: Semantics given by tool. All selections 

okay* 

yhen a selection is nrade* . a selector cede argument is given to 
"opointsel n . formally it looks only at strinas with an exact 

match* except: 

i * arg <= i: Anything is elegible, 

if selcd = <* Case is checked by parsef unction • 

(Using arg = 2 is not normally done,^ 

string-id 

An identifier for a string in a specified window. 

st ri nc-l i st 

A list of string element records. There is one element for 
each string in the specified window, ach string element 
record (sMst) is referenced by a string-Id and contains s 
pointer to either a linseg-list or a text string. 
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tool code 

A WORT that unicueLy identifies a tool 

tool List 

A list that contains* for each tooL for a given job* the pair 
tool code and window-id (window-id of that tool's primary 
wi ndow ) • 

window 

A rectangular area of the display screen* 

window oriority 

An integer used to determine which of the overlapping windows 
will show. A "privis bit" is set for each window that 
indicates if the window is visible due to priority. 

window-id 

An integer that designates dispLay window or other channel. 

window-l 1st 

Contains the window-table-address for each window. Indexed by 
window-id • 

window-table 

Contains all the information pertaining to the given window* 
incLudina the strinc-List address. 
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PROCESS COMMUNICATIONS INTERFACE (PCI) MODULE 



Introduction 



The c roc3ss Communications Interface Module (PCI) interfaces the 
Frontend to the communications media* arte hence to other 
processes such as tools and the Works Manager. As described in 
AN INTRODUCTION TO THE FRONTEND C23* there is a PCI for each 
communication mediums each PCI supplying the same interface to 
the Frontend. The primary functions of the PCI are to provide a 
way ^or the Frontend to call remote processes* and for those 
remote processes to call Frontend (externally callable) functions 
and to allow for character-oriented communication. 



Imoortant Data Elements 

The primary data element of the PCI is the process record 
'processrS which contains information necessary to communicate 
with a remote process. The actual information may differ 
depending on the communication medium* but it would typically 
include the process name and other identifiers for the process or 
connections to it. The process communication buffers record 
»pcorsrec* is another important data element* containing pointers 
and addresses of send and receive buffers. 

Character oriented communication is implemented as a Telnet 
network connection between the Frontend >;nd the other (tool) 
process. A data element* the Telnet control block (TCB)* is used 
to maintain each such connection the Frontend establishes. 



PCI Procedures 

The following procedures are used by the Frontend. 

ipcinit ( -> ) 

This procedure has no arguments and no results. It is celled 
at initialization time so that the PCI module may initialize 
itself. 

ipenew^ram ( instance REF -> ) 

Th<* single argument ^instance* is a grammar instance name* The 
procedure initalizes the process record for the remote process 
which that grammar will make calls upon. It is called each 
time a new orammar instance is created. 
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iocenccras! ( instance RF.F -> > 



This procedure is analogous to Mpcneworanr* and is called 

wh -never a grammar instance is no longer tc be usee by the F! 



ipccall C 



n 



Ff outofline -> ) 



The procedure Mpccall* performs the Cell on a remote process. 
The first argument is a CHL function name identifier. The 
boolean »outoftine* indicates whether the PCI is to wait for 
the remote reply or return as soon as possible* processing the 
remote reply at a later time (FALSE imrlies waiting)* This 
procedure decodes the parameters in th<= function name block* 
sets up the data to be communicated* and initiates the 
transmission. 

ipenetrec ( echo* netinjfn* netoutjfn -> telcb ) 

This procedure is called to set up a character oriented 
(Telnet) connection to a tool. The call is made after the 
connections are established* but before they are used in any 
way • 

The argument ♦echo t is TRUE only if input echoing is to be done 
by the Frontend. (Mormally echoing is cone by the tool.) The 
arguments f netinjfn* and f netout}fn f are handles on the Mnput* 
(with respect to the Frontend) and the •output* connections of 
the Telnet pair. The single result is the address of the 
Telnet control block for this connection pair. The procedure 
calling *ipcnetrec* must remember the TCB address and delete 
the TCE when it closes the connection pair. This is usually 
done by a parsefunct ion* such as *f etermtelnet *. 

Telnet control 

otiation strinc to 

TENEX 

ad characters from 

end fork when 

terrupt routine 

characters as 

n negotiation by 

I or writing them in 

It the information 

t control block for 

several such 
together and 



Th 


is oroced 


ure ere 


ates and initializes 


the 


bl 


ock* send 


ing an 


initial Telnet option neg 


th 


e server 


Telnet 


at the tool end. In 


the 


1m 


plementation* it 


creates a sub-fork 


to re 


th 


e connect 


ion and 


interrupt the main 


"ront 


ch 


sracters 


are ava 


liable. The main fo 


rk in 


*x 


telnetpsi 


• (in PCI) then disposes of 


the 


appropriate 


: it will reply to Telnet 


optio 


ei 
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characters to the termina 


th 


e proper 


window 


of the display screen. A 
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xtelnet 
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e connect 
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The following PCI procedure is called when 
on the Frontend. 



a remote call is made 



docall ( inbuf SEF* cutbuf B.ZF * cutbufsiz -> resler ) 

The procedure *docall* performs the calls on externally 
callable Frontend procedures on behalf of remote processes. 
Its first argument is the address of the input buffer* which 
must contain a message-oriented procedure invocation of the 
form defined in Appendix 1 of A GUIDE TO THE CLI AND CML. 

The procedure fdocall* removes the parameters from the 
top-level list (e.g.* message type* procedure name)* 
initializes the output buffer *outbuf* for the results (if 
necessary)* and calls the designated procedure. 

To read the data types and values in the message* *docall» uses 
the Data Representation Interface routines. It also passes on 
the port identifiers for the coroutines to the externally 
callable procedure. That is* every Frontend externally 
callable procedure is called with two arguments: the port 
identifiers of coroutines to read and write data structures* 
respectively. At the time of the call* the position within the 
♦input* dcta structure is such that the first element read is 
the first argument for the external call; likewise* the first 
element written in the output structure will be the first 
result* and so forth. The externally callable procedures are 
responsible for correctly reading their arguments using the 
port identifiers provided and building any resutt structures. 

The following are externally callable procedures* described in 
Appendix 4 of A GUIDE TO THE CML AND CLI. They reside in the PCI 
module because most of the functions they perform involve the 
communications media. 

f eopenconn—whose internal name is eopenconn. 

fectosconn — whose internal name is eel sconn. 

fetermtool — whose internal name is etermtool. 
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DATA REPRESENTATION INTERFACE 

Int rociuctior 

This section describes the L1Q coroutines used to read/write PCP 
data structures. PCPE8 is described in ■ GUIDE TO TFE CML AND 
CLI» Appendix 3* "Frontend Data Representatin for Message 
Communication". Since PCP data structures are sequential (i.e.* 
there are no Links)* it is necessary to keep track of the current 
position in the structure while it is being encoded cr decoded* 
L10 coroutines can perform the task of holding the current 
oosition* and thus are well suited to the encoding ard decoding 
of PCP data structures* 

Two things should be noted before we continue: 

These coroutines assume the PCPB8 type PAD. 

The coroutines are generally useful* ard compatible on a PPP-io 
CPCPB36 or B8> and PDP-11 CPCP88)* 

Reading a PCP Data Structure 

RLIST (adr REF* zone -> Ciportj) 

To read a data structure* openport on rlist* providing the 
address of the PCP data structure (f^rst word)* and a free 
storage rone. The returned port ID will be used subseouently 
to read elements from the data structure* as described below: 

rtype _ PCALL Cipcrtl (type* length* dest: value* ptr) 

*rtype* is the actual element tyoe * 

•type* designates the expected typ? of the elementCs) to be 
read or a special operator. 

• length • is a count of the number of elements of type 
*type* to read into array *dest*. 

♦dest* is the address of an array to store element values 

in. 

♦value* is the element value or a pointer. 

♦ptr* is an address into the data structure that can be 
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used t^ reset ycur position to this point in the data 
structure. 

The following are typical uses of cne rlist PCALL: 

rtype _ PCALL Ciportl (0: value? 

Will read one element of ANY type, dest and length need 
not be soecified here when type is zero. 



PCALL Ciportl (pcpindex* Sarray* 5)» 

Will read 5 indexes and store the values ir an array 
starting at 'array*. 

PCALL Ciportl (pcplist: listlen ; 

Will read one element* which n^ust be a list. An abort 

will or cur if it is not a list Cerr is called). The 
list length will be stored in listlen. Subsequent 
PCALLs will obtain the list elements. 

In the above examples the returned f ptr* was icnored. It 
could also have been stored. 

These types are possible (see A GUIDE TO THE CI^L AND CLI* 
Appendix 4* for PCP type values): 

type = pcpany (=0): 

Any PCP d3ta type except PAD is returned. The dest and 
length parameters* if present* are ignored. 

typ a = pcplist 

Here *dest* is ignored. An abcrt is generated if the 
element is not a list* or if it does not have Hength* 
elements. The value returned is the number of elements 
in the list. Subsequent PCALLs will resd the list 
elements. There is no indication of when the end of 
the list is reached? the element following the list 
will be returned after the last list element is 
returned* 

type = pcpboolean* ccpindex* pep mpty 

The type must match the element(s) being read cr an 
abort will be generated. The value returned is the 
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value of the element. Zero is returned for an e?*pty 

element* 

type - ocpinteger 

It is tricky to enable similar implementat ions on the 
PDP-10 and PDP-11. If the element is being returned as 
a PCALL result* the value wilt be the address of the 
integer (32 bits)* which must be moved before the next 
PCALL. If the element is being stored in an array* 32 
bits 'will be stored at the given location. This is a 
word on the PDP-10 and two words on the PDP-11* of 
course. 

type = pcpcharstr 

The character string is moved to the free storage zone 
and the address of the string is returned* On the 
PDP-11, if the zone is 'dpyzone** the string is net an 
a-string but is compacted? there are no M and L words 
and the length is in character zero. 

type = peppad 

Pads are ignored and will never be returned* this will 
always fail. 

type = rl isti gnore(lQO) 

This will cause the next *length» things to be ignored. 
They may be lists. This PCALL returns after advancing 
through the data structure. The type and value results 
are unspecified* but *ptr* is correct. 

type = rlistreset (103) 

This will re-establish the position in the data 
structure to that given by 'length*. It must be a 
pointer obtained from another rlist PCALL (third 
result). The type and value results are unspecified* 
but *ptr* is correct. The next PCALL will return the 
element following the one that was returnee when the 
pointer was obtained. 

type = rlistzonedOl ) 

This will set the zone that rlist uses for storing 
pcpcharstr*s to the value given as Hength.* It does 
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not advance through the data structure. The type and 
value results are unspecified* but *ptr 9 is correct. 

tyoe = rl istnop <102) 

This does nothing. The type for the next element is 
returned* but the value is unspecified* anc f ptr» is 
correct. It can be called to obtain the current 
position without advancing and or get the type of the 
next element without actually reading it. 

If *cest- is non-zero AND 'type* is charstr* then 
integert index* empty* or boolean 'length* elements are 
read and stored at location f cest»» In that case an 
ABORT is generated if the next *length» elements are not 
of type 'type*. 

If *dest f is non-zero* f type* may not be pcplist type* 
That is* only non-list elements rsay be stored in a 
designated arrays 

The result type and value are summarized here: 

rtypet value 



list! number of elements 

index: the index value 

integer: the address of 32 bits 

(On 11* first word is most significant) 

charstr: the address of the string 

boolean: TRUE or FALSE 

empty: zero 

bitstr: address of bitstring 

IMotes: 

Currently* the ABORT takes the form of a procedure call 
to err(S"Sad PCP data type -RLIST")? . 
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Examples * 

OPLiNJPnRT rlist (Rparams ? zone: Ciport3) 

% read one element of type index, put it in incexvalue % 

PCALL Ciport Kpcplndext 0: indexvalue) 

% read three booleans into array a ry % 

PCALL Ciport} (pcpb.oolean* $sry» 3)? 

% read one elementt either index or list % 

type _ PCALL Ciportl (0: value) 

CASE type of 

=pcoindex: ... %value is in 'value* % 

=pcplist: ... % length is in 'value* % 

% read entire list of charstrings into •str t array 
% 

PCALL Eiportl (pcpcharstrt $str§ value)? 

ENDCASE err($ w wrong type element"); 

Writing a PCP Data Structure 

WLTST (adr REF . n -> Coportl) 

Openport on ? wlist* takes the adcress of a block in which to 
build the data structure and a word count representing the 
number of words available in the block. A HELP signal 
requests more room if the block is overrun. 

Each subsequent PCALL on oport builds one element in the data 
structure (approximately). The PCALL arguments are type and 
value. yLIST always returns a WORD count and a pointer. 

count _ PCALL Eoportl (type* value: ptr)? 

'type* is a PCP data type or other special operator. 

'value* is usually the value of the PCP element. 
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f count* *s a WCRC count of the structure so far. 

»otr f is a pointer that czn be useci to reset the position 
in the data structure. 

The types allowed and the action taken are as follows* 

type: action 

pcpindex: 

Element of type index* value 'value* is constructed, 
pcpboolean? 

Element of type boolean is constructed* 

<value=C = FALSE) 
pcpempty : 

Empty element is constructed* 

pcpinteger: 

f value* points to 32 bits usee to make integer element* 
On 11* most significant 16 bits is first word* 

ocpcharstr t 

'value* is the address of an L1Q string* An element of 
type charstr (containing that string) is constructed* 

.pcpbitstrl 

*value* is the address of a bitstring* The first word of 
the bitstring is taken as an integer* which is the number 
of bits in the bitstring* 

pepli st: 

If •value* is zero* a list of unknown length may be 
built* Otherwise the list length is taken as *velue* and 

appropriate checks are made. 
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r> c p p a d • 

One PCP-PAD element is c erst rue ted. 

wlist ?nd (2 00) : 

This closes the last List construction. If the length 
was provided* a length check is made and err is called if 
not correct. Otherwise the length is computed and stored 
in the list element. 

wlist reset (201 ) : 

This resets the writing position to *value»* which must 

have been obtained from wlist previously as a f ptr*« The 

next element written will follow the last element written 

when the »ptr* was obtained. 

This is dangerous! After doing this* you may NOT close a 
list (wlistend) that was started BEFORE the wlistreset 
was done. The *count* after doing a wlistreset will be 
the number of words to the current position in the list* 
not the total number of words in the data structure. 

wl istnop (202) : 

This is a NO-OP that returns *cotnt* and •ptr* for the 
current position. 

Mote thst lists may be nested and data structures may be 
built without prior knowledge of the contents. 

If WLIST overruns the area! 

A HELP (wlistoverf low* address* needed) is generated* 

where f address* is the address of the first word of the 
area* ana ^needed* is the number of words that MUST be 
present to write the next element. 

The proper return is RESUMECgothelo* newaddress* n>* 

where ♦newaddress 1 is the address of the relocated area^ 
and *n» is the number of words allocated in that new 
area. 

The helping routine must copy the entire area into the new 
area. 
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USER PROFILE DATA STRUCTURE A\ ! D TOOL 



Introduction 



User Profile refers to the per node data base that holds 
parameters describing the desired tool-ir.dependent 
characteristics of the FE. The dynamic cata base is read when a 
node session begins and is used throughout the session to give 
the user a personalized FE. 

The User Profile Tool is a separate* fully split NSy tool that is 
accessed through the Runtool command given to the WM EXEC. This 
tool gives the node the ability to modify his own User Profile 

cata base* 



Current Capabilities 

The User Profile data base is not currently supported by either 
the WM or the FE* If the FE did read the User Profile data base* 
any modifications made in the User Profile Tool would becoire 
active at the next session* when the User Profile would again be 
res6 by the FE. Currently the User Profile Tool reacs and writes 
the data base to a Tenex file that is uniquely named (using the 
project-node name). 



envisioned Capabilities 

Whils the User Profile has never been fully integrated into the 
NSW* it is envisioned that the User Profile be a data base whose 
access is restricted by the WM Ce.g. as en NSW file, cr through WM 
calls to read/write it). At session startup* it would be read by 
the ! JM and returned as a PCPB8 data structure as a result of 
WMLOGIN. 

The User Profile Tool would provide inuneciate profile updating 
and the option to make the modification permanent or restrict it 
to the current session. To support immediate profile updating* 
the FE would provide an external call* allowing it to read a 
profile or profile-part from the User Profile tool. 
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User Profile Dat3 Structure 

D^ta Structure 

The User Profile data structure consists ci one list (ceded 
in PCPB? containing the following five elements (in order): 

1. Profile - SITSTR 

Feedback? herald* etc. See definition of fields belcw» 

2. Stsrtupstring - CHARSTRING 
Startup input command string. 

3. Tool I1?t - LISTC tooll* tool2f ... ) 

Each element tool-i is of type CHARSTRING and contains a 
legal name of a tool* 

4. Control Character list - LIST (Referred to as cntchr 
list.) 

Each element of the list is itself a LIST (referred to as 
dvclst) of the following structure: 

LIST(index» LIST(cf »char*echo) * LIST(cf *char*ecno) * ... 
> 

where: 

index - INDEX - device code 

cf - INDEX - Control function code 

char - CHARSTRING - String of characters where each 
serves the specified function 

echo - CHARSTRING - String to echo when the control 
character is typed. 

5. Version - INDEX 

For compatibility check. 
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Dsta Structure Conventions 

1. The profile bitstr is currently 3 bits Long* with the 
bits 3llocated as follows (bit number 1 is the leftmost): 



Field 
feedback Length 
heralo length 
recognition mode 



Bits 

1 thru 8 

9 thru 12 

13 thru 14 



secondary recognition 15 thru 16 

promoting 17 thru 18 

command word length 19 thru 23 

In the L10 programming Language this results in the 
following record: 

Cprfl) RECORD 

padd1ngC93* cmdwdlenCSjf prptC23» rcg2C23* rcgC23* 
hldlen'43* fblenC83 ; 

2. Startup string is a null string if none is specified. 

3» Tool-list convention: 

First element is the entry tool* or NULL if none is 
defined* (Undefined entry tool causes the user to stay in 
the EXEC after Login.) 

Other elements (if any) are tool names (all as strings). 
4. ControL characters! 

If a list for a specific device (dvclst) does not exist all 
control characters default. 

If a list exists for a specific device only these 
control-characters that deviate from the default have 
entries. 

If this entire control character list has only one NULL 
element all controL characters for all devices default. 
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5. Version number is currently 9* 

f*e.*ninQ of Fields in the Profile citstr 
Prompt 

- Verbose (default value) 

1 = Terse 

2 = Off 
Recognition (Both Levels) 

- Anticipatory 

1 = Terse (default value) 

2 = Fixed 

3 = Demand 

Feedback length* her3ld length* and command word length 
contain the correspond™ c length (in characters) and default 
to the maximum number allowed. 
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Control Function Indexina and Defaults 



F u n c t i o r. 


Index 


Default 


COMMAND ACCEPT 


4 




ID 


COMMAND DELETE 


24 




I* 


REPEAT 






J p 


BACKSPACE CHARACTER 


8 




IH 


BACKSPACE WORD 


23 




ty 


BACKSPACE STATEMENT 


16 




IP 


LITERAL ESCAPE 


22 




|V 


IGNORE 





Nc 


Default 


SHIFT CHARACTER 


47 


No 


Default 


SHIFT WORD 


92 


No 


Default 


TAB 


Q 




II 


OPTION 


21 




fu 



Device Code Indexing 

Device Name Index 

II ? 

MVT 3 

LINEPRQ-CESSGR 4 

IMLAC 5 

EXECUPORT 6 

TTY33 7 

TTY35 8 

TTY37 9 
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GENERATING a mew frontend 

Int roduc 1 1 en 

The following steps must be taken to create a new Frontend: 

- Make sure the relocatable binary files are up to date* 

- Load the desired Frontend configuration to create a save 
(.SAV) file. 

- Create the initial grammar. 

- (Other steps may be necessary depending on the Frontend 
configuration.) 

The actual leading process is usually done by a RUNFIL program* 
with a RUNFIL file available for each Frontend configuration. 
All compiling, loading* and saving operations currently must be 
done on a TENEX or T0PS-2G best. 

Compil at ion 

Each Frontend source file contains the name of the compilerfs) 
and the REL fileCs) that are to be used when compiling that 
source file. To create a Frontend fc-r the PDP-10* use the L10 
compiler* for the PDP-11* use the L1G11 compiler. Of course* if 
the source file has not been changed since the existing REL file 
was created? it is not necessary to compile that source file 
before creating a new Frontend. 

Frontend source files are currently NIS iles. To compile them* 
use the Complie File command in the Programs subsystem. 
Sequential files may be compiled by simply running the same 
compiler as a TENEX subsystem* giving the sequential file as 
input* and specifying the REL file as output. 

Loading 

To load a Frontend* run a loader to bind all the REL files 
together and save the core image in a SAV file. For a PDP-11 
Frontend* you must also format the SAV file into PDP-11 load 
format. The names of the RUNFIL files that perform the loading 
*or each Frontend configuration are specified below* along with 
the names of the various files that comprise each Frontend 
module. 
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To m^ke a Frcrtenc ready for use* the SAV file is placed in th' 

•Hie directory in which it is to run* The initial grander is 

Dlaced in the same directory with the nave £XEC*CGftl parse 

function files are also placec i n the directory* with the 



extensions 



tpr 



(for code) or *PFD (for data). This is explained 



in the "Grammar Compilation artti Compaction" section of A GUIDE TC 
THE CWL AND CLI* 

In some cases* the Frontend is then ready to use* The exceptions 
sre a stand-alone single fork tool that uses the Frontend and a 
Frontend that uses the shared page communication medium* In the 
first case* refer to "Making a Stand Alone Tool" in Appendix 2 of 
A GUIDE TO THE CML AND CLI. For the second case* the SAV file 
for the tool backend must be placed in the same directory as the 
Frontend* along with the Frontend and the initial grammar* 

When making s PDP-11 Frontend* an additional step is performed by 
the RUNFIL file. The SAV file is converged into PDP-11 loading 
format* by way of program SAVBIN. The resulting EIN files are 
then loaded on the PDP-11.. Because that loading process is still 
undergoing changes it will not be described in detail at this 
t i ir. e • 



i-rontend Files 

Below is a list of the Frontend source files* the REL files they 
produce* and information about which Frontend conf igtrat ion 
requires them* ^hen no file directory is given* the directory is 
<NSU-SQURCES>. Where several REL files ere produced from one 
source* they are separated by a semi-colcn (» )• The L10 runtime 
support -Hies (code and data) are not included in this list* but 
they are loaded in each Frontend configuration. 



NEVCLI.NLS 

NEWCLI.REL; required for ALL PDP-1G FEs 
<L1011>CLI.REL; required for ALL PDP-11 FEs 

L1Q11STGMGT.NLS 

FESTGMGT.REL; required for ALL PDP-10 FEs 
<L1011>FESTGKGT.REL; reouired for ALL PDP-11 FEs 
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XOSI-CLI • NLS 

XOSICLI.PEL; XOSIDATA.REL; requirec for ALL PDP-1C FEs 
CG?FADDS»NLS 

PFADDS.REL* recuirec for ALL PDP-10 FE-: 

<L1011>PFADDS-REL: required for all PDP-11 FEs 
XFEROUTIMES.NLS 

XFERTNS.REL; required for ALL PDP-10 Fts 
XFEDATA.NLS 

XFEDATA.RELt required for ALL PDP-10 FEs 

<L1011>FEDATA.REL; required for all PDP-11 FEs 
DPYPKG.NLS 

DPYPKG.RELt reauired for ALL PDP-10 FE* 

<L1Q11>DPYPKG.REL: required for ALL PDP-11 FEs 
DPY-10.NLS 

DPY-1G.REL; required for alt PCP-1Q FEs 
MSG-3I.NLS 

MSG-3I.REL; MSG-3DATA.REL: required for MSG-3 
TYPECLI.NLS 

TYPEI.REL: required for TYPEOUT 
SAFE. NLS 

SAFEI.REL* required for Stand Alone FE 
<RELNINE>NLSI.NLS 

<RELMINE>NLSI.REL* required for Shared Page 
PCPBfi-lO.NLS 

PCPB8.REL? required for MSG-3* Raw Net Corn- ard Shared Page 
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<L1911> c CP5e-ll •MLS 

<L1Q11>PCP93.REL? recuired for "all PDP-11 per 
CGRAMLDR »NLS 

CGRAMLDR.REL; recuired for ALL PDP-10 FEs 
<L1D11>DPY-11.MLS 

<L1011>DPY-11.REL; recuired for all PDP-11 FEs 
DPYDATA-10.NLS 

DPYDATA.REL? required for alt PCP-10 FEs 
<L1011>OPYDATA-ll.NLS 

<L1011>DPYCATA # REL; recuired for all P r P-ll FEs 
MS63FE.RUN 

RUNFIL input to make MSG-3 Frontend 
TYPECLI.RUN 

RU.MFIL Input to make TYPEOUT Frontend 
<RELNINE>NLS9FE.RUN 

RuMFIL input to make Shared Page Frontend 
SAFE .RUN 

RUF'JFIL input to make Stand Alone Frontend 
<TL1011>CLI.RUN 

RUNFIL inout to make PDP-11 Frontend 
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